home *** CD-ROM | disk | FTP | other *** search
/ Mac Magazin/MacEasy 32 / Mac Magazin and MacEasy Magazine CD - Issue 32.iso / Grafik & Text / OzTeX3.0 / BibTeX / BibTeX.ReadMe < prev    next >
Text File  |  1997-02-14  |  20KB  |  424 lines
  1. # ###################################################################
  2. # 
  3. #  FILE: "BibTeX.ReadMe"
  4. #                                    created: 4/2/96 {6:50:21 pm} 
  5. #                                last update: 14/2/97 {10:38:42 am} 
  6. #  Author: Vince Darley
  7. #  E-mail: <mailto:darley@fas.harvard.edu>
  8. #    mail: Division of Applied Sciences, Harvard University
  9. #          Oxford Street, Cambridge MA 02138, USA
  10. #     www: <http://www.fas.harvard.edu/~darley/>
  11. #  
  12. #  Mac port copyright (C) 1996 Vince Darley.
  13. #
  14. #  Freely distributable, please report bugs (and fixes) to
  15. #  the author.
  16. #
  17. # ###################################################################
  18.  
  19. This is BibTeX (fat)
  20. ====================
  21.  
  22. Contents:
  23.  
  24.     (i)     Description of BibTeX's function and purpose.
  25.     (ii)     Feature list for this version of BibTeX for MacOS.
  26.     (iii)     Using BibTeX with the editor 'Alpha'
  27.     (iv)      Apple-events and BibTeX
  28.     (v)      Technical details, compilation, to-do's,...
  29.     (vi)    Version history.
  30.  
  31. BibTeX is the bibliography handling tool related to the TeX/LaTeX 
  32. typesetting system (available on almost all conceivable OS platforms).  
  33. When a document is typeset with LaTeX, an auxiliary file (with extension 
  34. '.aux') is generated.  This auxiliary file contains, amongst other things, 
  35. a list of references (to books, articles, research reports, web-url's,...)  
  36. cited in the original document.  BibTeX takes this list, together with the 
  37. name of a style file (extension '.bst') and a list of bibliography 
  38. databases (extension '.bib') which are also given in the auxiliary file, 
  39. and produces a wonderfully formatted list of references which the LaTeX 
  40. system subsequently (and automatically) appends to your typeset document.
  41.  
  42. Hence BibTeX is really not at all useful without TeX/LaTeX (there are 
  43. several freeware/shareware/commercial versions for the MacOS: OzTeX, 
  44. CMacTeX, DirecTeX Pro, Textures).  In fact this port of BibTeX is now 
  45. distributed with OzTeX 2.0 or newer (although the actual version shipping 
  46. with OzTeX can lag behind the latest by a release or two).  It is useful 
  47. to have a good text editor which knows about the particular format of LaTeX 
  48. documents: on the Mac, the editor Alpha is indispensible in this regard, 
  49. both for editing and for its apple-event communication with the various 
  50. parts of a LaTeX system.
  51.  
  52. For those who think this sounds a bit too complicated, the benefits in 
  53. terms of quality of output (both textual and mathematical) and automatic 
  54. generation of all manner of numbering schemes (figures, equations, 
  55. sections), and document parts (table of contents, index, bibliography), 
  56. together with cross-platform availability, mean that many people consider 
  57. it the _best_ current system for producing quality documents.
  58.  
  59. Here are some links for further information:
  60.  
  61. •    Mathematical relevance: <http://e-math.ams.org/>
  62. •    General TeX documentation: <http://www.cl.cam.ac.uk/TeXdoc/TeXdocs.html>
  63. •    Archive of LaTeX documenation: <http://www.loria.fr/tex/english/index.html>
  64. •    More LaTeX links: <http://molscat.giss.nasa.gov/LaTeX/externals.html>
  65. •    The editor 'Alpha': <http://www.cs.umd.edu/~keleher/alpha.html>
  66. •    Various TeX-related links: <http://www.bluesky.com/TeXlinks>
  67. •    CMacTeX: <http://www.math.tamu.edu/~tkiffe/cmactex.html>
  68. •    OzTeX: <http://www.kagi.com/authors/akt/oztex.html>
  69. •    Textures: <http://www.bluesky.com/>
  70. •    Archive of all TeX related material: <http://jasper.ora.com/ctan.html>
  71.  
  72. Many thanks to Alun Carr, Andy Amann, Richard Chang, Jacques Distler, and 
  73. others for helping to track down the bugs my port of BibTeX has had, and 
  74. for suggestions on how to improve it.
  75.  
  76. ========================================================================
  77.  
  78. BibTeX version 1.1.6
  79.  
  80. It has no known bugs, however, use at your own risk; there is no 
  81. warranty....  
  82.  
  83. Feature list: 
  84.  
  85. •    Basic features
  86.    -  Processes .aux files
  87.    -  Examine new or old log files and cmd-click to jump to errors, 
  88.       warnings, etc. in your editor.
  89.    -  Very fast (now more than 10 times faster!).
  90.    -  Friendly to other applications (actually calls WaitNextEvent);
  91.    -  Fat binary; runs on PPC or 68k machines;
  92.    -  Copes with both Unix and Mac standard eol characters.
  93.    -  Internet Config aware
  94.  
  95. •    TeX details:
  96.    -  Switchable between 'big' and 'small' modes.  The 'big' mode increases
  97.       the size of biobiography resources such as the number of strings allowed.
  98.       This should let you use 'Camel' the up-and-coming bibliography stuff for
  99.       LaTeX2e;
  100.    -  Search path (for .bib, .bst files) is as follows: (1) The two paths 
  101.       you set in the options dialog (2) the "BibTeX inputs" folder, 
  102.       (3) the location of the '.aux' file being processed.  This search 
  103.       path is used for both .bst and .bib files, although you can of course 
  104.       keep them in separate directories if you like;
  105.    -  Source code available;
  106.  
  107. •   Interface details:
  108.    -  Supports high-level apple events etc. so you can drag a '.aux' file (or 
  109.       several) onto it for processing, or send it an odoc event from Alpha...
  110.    -  You can command-click on warnings, errors and filenames in
  111.       the log window to leap to the correct file, line, error position
  112.       etc. in your favorite editor.  Read the section 'Apple-events and
  113.       BibTeX' for more details.  
  114.    -  Links from the about box to the BibTeX web page, so you can check
  115.       for upgrades.
  116.    -  If available, it uses Internet Config for file types of the .blg, .bbl 
  117.       files it creates.  If you make BibTeX ('Vbib') the creator of
  118.       .blg files, you can double click them to open them in the log window.
  119.    -  Balloon help is available for all dialog box items.
  120.    
  121.    
  122. This version of BibTeX is totally free.  If you like it, feel free to
  123. send email, postcards, cash, registrations to shareware you've written,...
  124. but there is no obligation.
  125.  
  126. Note that the application's partition is generous at 400k by default.  I 
  127. think it should work with 390k on 680x0 machines, and 300k on PPC machines, 
  128. so you could lower that size.
  129.  
  130. Things to do after installation:
  131.  
  132. -    Open Internet Config and set the type/creator of '.blg' files to be the 
  133.     BibTeX application.  Then you can double click to open them in BibTeX.
  134.     NB. For cmd-clicking to work, you must have Internet Config installed.
  135.     
  136. -    Download Alpha if you don't have it
  137.     
  138. -    Install the Alpha-communication scripts (read "bibEngine.tcl" 
  139.     for details).
  140.     
  141. -    Download "Vince's Additions" to make your Alpha/BibTeX/LaTeX experience 
  142.     even better!
  143.  
  144. ========================================================================
  145.  
  146. Using BibTeX with Alpha
  147.  
  148. As well as the scripts which allow command clicking in the log window to 
  149. send Alpha to the correct file/line/entry/error/...  there are other 
  150. features of Alpha which will make editing LaTeX documents a more pleasant 
  151. task.  First of all there is the TeX mode for Alpha written by Tom Scavo 
  152. which is great.  Second, I've written a package of add-ons for Alpha, 
  153. called "Vince's Additions".  It provides a large number of improvements to 
  154. TeX mode, including 'completions'.  This allows you to type something 
  155. short, hit <cmd-Tab> and have Alpha extend what you typed into something 
  156. more useful.  The types of things which can be completed range from: words, 
  157. TeX-commands, environments ('\begin' is expanded into an entire 
  158. environment), references ('\ref{my-long-r' is expanded into the name of a 
  159. nearby '\label'), and even citations: '\cite{Smit' will be expanded into
  160. the correct bibliography entry which begins 'Smit'.  If multiply entries
  161. match, then you are presented with a list of matches, which also contains
  162. the title of each match, so you can easily select the correct one, without 
  163. having to bother opening you bibliography file at all.  You can download
  164. this package either from Alpha's web site, or from my own 'Downloads' page,
  165. which usually contains a more recent version.
  166.  
  167. If you don't have or use Alpha, download it immediately!  Make sure you
  168. pay the shareware fee.
  169.  
  170. ========================================================================
  171.  
  172. Apple-Events and BibTeX
  173.  
  174. BibTeX can be triggered to process '.aux' files by being sent a standard 
  175. 'odoc' event.  Versions of Alpha newer than 6.2 will do this without any 
  176. configuration on your part.  If you're using an old version of Alpha (pre 
  177. 6.2), download a new version (see the hyperlinks above); (Also have a look 
  178. at my package "Vince's Additions" which contains some useful bibliography 
  179. conversion tools).  If you don't have Alpha, download it immediately; it's
  180. easily the best editor for TeX, LaTeX, C, C++ etc. (IMHO).
  181.  
  182. As of version 1.1.4, command-clicking in the log window will now send GURL 
  183. 'bibresult' events.  To make use of these, open Internet Config, select 
  184. 'helpers' and 'add' a helper for 'bibresult', and select as helper your 
  185. editor.  Of course your editor needs to be able to receive and interpret 
  186. GURL bibresults.  I've enclosed some procedures for Alpha which do this, 
  187. but if you use BBEdit/TeXtures or something else, you're currently on your 
  188. own.
  189.  
  190. The format of the 'bibresult' GURL event is as follows:
  191.  
  192.     bibresult:FULLFILENAME:MESSAGE
  193.  
  194. where FULLFILENAME is a full path description to the base '.aux' file or
  195. 'Unknown', and MESSAGE is any of the following:
  196.  
  197.     The top-level auxiliary file: FILENAME.aux
  198.     A level-X auxiliary file: FILENAME.aux
  199.     Warning--I didn't find a database entry for "ENTRY"
  200.     Database file #X: FILENAME.bib
  201.     Warning--WARNING ENTRY
  202.     The style file: FILENAME.bst
  203.     ERROR---line LINENUM of file FILENAME a 'UP-TO-ERROR' at POSITION
  204.  
  205. where X is an integer; FILENAME is a just the name, with no path given;
  206. ENTRY is a citation key such as 'Darley1996'; WARNING is a standard
  207. BibTeX warning (such as 'empty title in'); ERROR is a standard BibTeX
  208. error (such as 'Repeated entry'); LINENUM is the line number of an
  209. error; POSITION is the character position in that line at which the
  210. error was detected; UP-TO-ERROR is the string of characters from the 
  211. beginning of the line to the start of the error, with braces {} replaced 
  212. by ‘’ because of some IC/AE problem.
  213.  
  214. The Tcl procedures I've written for Alpha interpret these messages and take 
  215. the appropriate action: opening a file; finding and highlighting an error; 
  216. adding a '.bib' file to the \bibliography environment; making a new entry 
  217. in an existing '.bib' file,… To use these scripts, read the file 
  218. 'bibEngine.tcl' which gives installation instructions.
  219.  
  220. Problems/Bugs:
  221.  
  222. Since BibTeX sends actual line numbers and positions, if you're correcting 
  223. a lot of errors/warnings, these line number can become out of date.  The 
  224. receiving scripts are designed to alleviate this problem (they search 
  225. locally for something matching the error), but with heavy editing, such 
  226. problems are not completely avoidable.
  227.  
  228. ========================================================================
  229.  
  230. Technical Stuff:
  231.  
  232. To Do:
  233.  
  234. •    Write to .blg and .bbl files asynchronously (actually not that useful).
  235. •    Some minor code tidying.
  236. •    Incorporate updated powerplant classes when available.
  237. •    A few _minor_ speed improvements are still possible.
  238. •    Perhaps switch to using WASTE, instead of TextEdit (memory impact?).
  239.  
  240. Any offers for help or suggestions for improvements much appreciated --- in 
  241. particular if someone wants to get to work on the to-do's, that'd be great.
  242. If you have example code which does something similar to any of the to-do's
  243. (e.g. asynchronous file i/o), and you're happy to let me use it as a 
  244. template, then please send me it!
  245.  
  246. ------
  247.  
  248. Sources:
  249.  
  250. I'm no longer distributing the sources, since it seems a bit needless, but
  251. if you actually want them, just ask.  
  252.  
  253. Based on the C code of the original MacBibTeX (0.99c) which I grabbed from 
  254. CTAN, and code generously donated by Rick Zaccone from his 'Makeindex'.  
  255. Icon adapted from one I grabbed off a folder from some collection on the 
  256. net.  'IC++' written by Dan Crevier is used for the about box links.  I 
  257. also use LBalloonTracker by Paul Lalonde which is © 1996 Corporate Software 
  258. & Technologies Int.  Inc.  (CS&T), and very convenient.  Many thanks!
  259.  
  260. ------
  261.  
  262. Compilation (with CodeWarrior 11):
  263.  
  264. Obtain the library 'MoreFiles' (preferably version 1.4.5 or newer), which
  265. should be available from the info-mac archives.
  266.  
  267. •    Open the source code folder
  268. •    Compile BibTeX68k.µ
  269. •    Compile BibTeXPPC.µ
  270.  
  271. Move the resulting application "BibTeX" up one level so it can find 'BibTeX 
  272. inputs'.  You may need to adjust the memory allocation (with Get Info), but 
  273. beyond that you're set.
  274.  
  275. -----
  276.  
  277. Personalisation:
  278.  
  279. You can now set BibTeX search paths using the options dialog, but if for 
  280. some peculiar reason you want to set more than two different paths, in 
  281. addition to the defaults, then you can do so using ResEdit:
  282.  
  283. You can edit a string resource with ResEdit to specify your own search 
  284. path.  To do this open the app with ResEdit and look at the STR# resource 
  285. called "Path".  You can add entries which look like this:
  286. '2:Hard Disk:My Search Path:'; the '2' signifies to BibTeX that this is
  287. a complete path specification.  If you prefer, '0:' indicates 
  288. a path relative to the .aux file, and '1:' relative to the BibTeX 
  289. application.
  290.  
  291. ------
  292.  
  293. Version History:
  294.  
  295. 1.1.6    Numerous small improvements and bug-fixes to the 'bibEngine.tcl'
  296.         scripts which handle the receiving end of apple-events from BibTeX.
  297.         Recompiled the application with Codewarrior 11.  Updated to 
  298.         MoreFiles 1.4.5, and MSL C/C++.  Few other minor code improvements.  
  299.         Click-drag scrolling works in the log window now.  Still no 
  300.         drag'n'drop though.  Changed app's memory allocation slightly.  
  301.         After a fatal error, memory is freed immediately now, previously 
  302.         allocations would accumulate until the end of a non-fatal run.  
  303.         Rewrote a few code sections so less of the MSL C library is linked 
  304.         in (reduced code size significantly).  Now use some styled text in 
  305.         the log window.  Improved a couple of error/help messages.  Rewrote
  306.         preferences file code using powerplant rather than a separate, rather
  307.         old library; makes for a much faster startup.
  308.         
  309. 1.1.5    Minor bug-fix in which some sorts of fatal bibtex error would 
  310.         ignore the 'stay open on error' flag.  Slight improvements to 
  311.         interaction with Alpha, and minor additions to the log file on some 
  312.         fatal errors.  Increased global strings to 15 (so it works with 
  313.         the indxcite package now).
  314.  
  315. 1.1.4    Copes with filenames containing spaces.  Remember if you use
  316.         spaces, your files will not work on other platforms.  Fixed a 
  317.         minor buffer-overflow problem in which not all warnings would
  318.         be given in the log window.  Added command-clicking features
  319.         to the log window (very useful and cool new feature!).  Fixed
  320.         one source of preferences problems (startup with no preferences
  321.         file, quit and restart => default preferences are garbage).
  322.  
  323.         Fixed crashing bug when cmd-clicking at the end of the log window.
  324.         Fixed a couple small GUI buglets.  Added processing time message
  325.         to end of log window.  Command clicking in opened .blg files sends
  326.         correct file information now.  Minor changes to about box, and to
  327.         Tcl scripts for Alpha communication.
  328.  
  329.         Fixed so prefs file has an icon; startup will be slow the first
  330.         time, because BibTeX will have to rewrite your preferences.  
  331.         Added an icon resource for TEXT files which can be used for .blg 
  332.         log files.  Set this up in Internet Config, and you can double 
  333.         click .blg files to launch.  Now you can look at old .blg files and 
  334.         decide if you wish to regenerate them (cmd-G = Go will reprocess 
  335.         the corresponding .aux file), or cmd-click to edit problems using 
  336.         your editor.  Fixed quite old (I think) bug in which you could have 
  337.         two log windows after hitting 'Cancel' in the options dialog.
  338.         Feature change: BibTeX now rejects any text file that's not '.aux' 
  339.         or '.blg'; before it would be passed to the core code and of course
  340.         cause errors.  Added more Balloon help.  Feature change: type/creator
  341.         of .blg and .bbl files created are taken from Internet Config if 
  342.         possible, if not then from the .aux file as before.
  343.  
  344. 1.1.3    Really fixed end-of-file problem.  Other minor changes.
  345.  
  346. 1.1.2   Fixed setting end-of-files correctly.  I somehow reintroduced this
  347.         bug when I rewrote all the file i/o stuff.  Balloon help in dialogs.
  348.         
  349. 1.1.1    Added options 'Stay open on warning', 'Stay open on error' which
  350.         counter-act the 'Quit when finished' option, and leave BibTeX
  351.         open if anything went wrong.
  352.         Fixed the 'text-jumping' visual bug in the log window (thanks
  353.         to a helpful soul on comp.sys.mac.programmer.codewarrior).
  354.         Updated to MoreFiles 1.4.3.
  355.         Preferences file now has its version number updated if necessary
  356.         when you start BibTeX, and I always create a preferences file now,
  357.         and any old preferences are updated with any new options.
  358.         This fixes an old 'bug' in which BibTeX would take a long time
  359.         starting up, because it's looking for a preferences file, or
  360.         trying to read information from it which doesn't exist.
  361.         Fixed a subtle 68k only bug which has been around for a long time,
  362.         but only now reared its head --- caused horrible crashes on 68k
  363.         machines, somewhat randomly since useful memory was being 
  364.         over-written.  However it's fixed now.
  365.         Fixed a small bug introduced in 1.10, which would show up only
  366.         after multiple runs, especially after a fatal error, and could 
  367.         result in a crash.
  368.         Added message to the log window after a fatal error.
  369.         
  370. 1.1.0    Did some serious profiling and optimisation.  Opening files is
  371.         really rather slow on MacOS, probably due to the emulated nature
  372.         of the file-system.
  373.         Now about 10+ times faster than 1.06.  Rough timing is as follows:
  374.         v1.06 75secs, v1.07 62secs, v1.10 7secs
  375.         (All using Speed Doubler on a 5300cs on a large BibTeX run) 
  376.         Huge rewrite of all the IO code: uses PowerPlant buffered IO classes,
  377.         which makes everything rather simpler, and on the whole a lot faster.
  378.         The code is much, much cleaner now, as I've cleared out a lot of the
  379.         old vestiges of MakeIndex and the ancient web2c source code has been
  380.         modernised.  Therefore the BibTeX <-> Interface links are simple now.
  381.         Added option to monopolise the CPU.
  382.         Significant interface improvements:
  383.         You can now set two folders to search in the options dialog box,
  384.         (but the old technique of using Resedit still works).  Note that
  385.         by default BibTeX now searches in:
  386.         • The same folder as the '.aux' file being processed.
  387.         • The folder 'BibTeX inputs' located wherever the BibTeX application
  388.         resides on your hard drive.
  389.         • Any folders you add manually using ResEdit (not normally necessary)
  390.         • The two folders you specify in your preferences.
  391.         Added links from the 'about box' to the BibTeX web-page, and to
  392.         mail me, etc.
  393.         Recompiled using Codewarrior 10
  394. 1.07    (Never released publicly)
  395.         Significant internal changes:
  396.         (i) Speed increases. 
  397.         (ii) Increased sizes of things for 'Big' mode.  This version of BibTeX
  398.         should support Camel (the up-and-coming LaTeX 2e bibliography system).
  399.         (iii) Added a couple of options which were requested: 
  400.         'beep when finished' and 'no log window'.
  401. 1.06    Now copes with extended character set 'üöé...'.  Not all TeX
  402.         implementations allow them, but if you pass one to BibTeX, it
  403.         will happily output it, assuming your version of TeX can cope.
  404.         Changed name of log window.
  405. 1.05    Recompiled with CW9, updated to take account of Powerplant
  406.         changes.  Cosmetic change when selecting 'go' to re-run
  407.         a file - the window is now cleared first.
  408. 1.04    Minor (non-fatal) bug fixes --- all files properly closed and 
  409.         flushed after a bibtex error, file eof's set correctly for .bbl 
  410.         and .blg files.
  411.         Thanks for the bug reports!
  412. 1.03    Minor changes --- it now gives a message 'BibTeX run complete.'
  413.         in the log window, rather than just finishing.  Documentation
  414.         update.  I've fixed the FREF/BNDL problems, so drag'n'drop
  415.         really should work now ;-)
  416. 1.02    Switchable between Big and Small.  Uses new memory allocation
  417.         scheme from Rick, so temporary memory is used rather than the
  418.         system heap.  This means the application's given partition can
  419.         be much smaller (300k works for me). Added fref 'TEXT' resource
  420.         which was missing previously (so drag and drop will work under
  421.         all circumstances now).
  422. 1.01    Copes with Unix as well as Mac EOL characters
  423. 1.0        Original; soon to be distributed with OzTeX 2.0
  424.